USER GUIDE - ENTERPRISE HOME SCREEN Version 2.0

Symbol Technologies, Inc.

Enterprise Home Screen (EHS)

User Guide

Revision M

May 2015

## Introduction

Enterprise Home Screen (EHS) is a replacement application launcher, for Symbol Android devices, designed to allow only specified applications to be launched.

## Glossary

User screen

Admin screen

Context menu

APK ( .apk )

  An APK is a software installation package built for the Android operating system.

## Installation

The following instructions assume that you have the device drivers installed and are able to read/write to the SD card on the device.

1. Connect the device to a PC via a cradle or USB adapter cup.

2. Copy the EHS Installer .apk file to the On Device Storage (SD card) folder of the device.

3. Open File Browser from the Android application launcher screen.

4. Navigate to the SD card and tap on the EHS Installer .apk file.

5. Tap on the Install button.

6. Once the application is installed, tap the Open button.

7. Tap the Home button.

8. Tap Enterprise Home Screen followed by Always.

9. Now reboot the device. This is mandatory.

| If the Done button was tapped instead of the Open button at step six above, go to App Drawer in the device and launch the EHS Installer app manually and continue from step seven above.

| If the Just once button was tapped instead of the Always button at step eight above, launch the Calculator app and continue from step seven above.

### Uninstallation

Uninstalling the EHS Installer app from the device will automatically uninstall the EHS app as well. But this automatic uninstallation of EHS app will not happen unless you have followed steps seven and eight above.

| Once installed, EHS changes some system settings in the device as given below. Uninstalling EHS or switching to another Launcher (Home screen application) will not revert these settings to the previous state. So if required, make sure to set them to the original state via Preferences or configuration files, before moving away from EHS. EHS default settings: Disable Settings and Search apps Bypass device keyguard (unlock) screen Disable Airplane/Flight option under Power menu Disable USB debugging (ADB) Restrict system settings Disable status bar Settings icon Disable accessing Camera app while on keyguard (unlock) screen Disable accessing Search app while on keyguard (unlock) screen

## User mode

This is the default mode in EHS. The user screen displays only the applications/links specified in the configuration. Tapping any of the displayed application icons will launch that application.

User screen with context menu showing

Pressing the MENU button will bring up a context menu from which you can access wireless and battery information, the tools menu and information about EHS.

## Tools menu

This lists the specified applications as a list and provides access to the admin mode.

Tools menu

To access admin mode, select the Admin Login option and enter the admin password when prompted.

Admin login

The number of failed login attempts is limited (default ten). The count of failed login attempts is reset on a successfully login. Once the number of failed login attempts has been exceeded, further login attempts will result in a message being displayed and the user will not be able to login any more. The xml configuration file has to be replaced to reset the failed login count and allow the user to be able to attempt to login again.

## Admin mode

This mode allows access to all the applications installed on the device.

This mode also allows applications to be added to and removed from the user screen.

- To add an application to the user screen, long press the application icon until a confirmation dialog appears then press OK.

- To remove an application from the user screen, long press the application icon until a confirmation dialog appears then press OK.

Admin screen showing context menu

Pressing the MENU button will bring up a context menu from which you can access wireless and battery information, the tools menu and information about EHS as per the user screen. Additionally, access is also provided to EHS preferences.

Tools menu showing Export Configuration File

Pressing the Export Configuration File menu will bring up a folder selection dialog. Exporting configuration file is restricted only to a limited folder set existing in the device such as;

- /storage/sdcard/Android/data/com.symbol.enterprisehomescreen/files/

- /storage/sdcard0/Android/data/com.symbol.enterprisehomescreen/files/

- /storage/sdcard1/Android/data/com.symbol.enterprisehomescreen/files/

- etc…

### EHS preferences screen

Once in admin mode, the context menu will include an additional entry which gives access to a screen where you can change EHS preferences. The preferences screen reads the values from the xml configuration file and any changes made are written back to that file.

## Configuration

Enterprise Home Screen is configured via an xml file found in the /enterprise/usr/ folder in the internal memory of the device. This file is read each time the User or Admin screen comes to the foreground.

Example Configuration:

    <?xml version="1.0" encoding="utf-8"?>
    <config>
        <kiosk>
            <application label="Calculator" package="com.android.calculator2" activity=""/>
        </kiosk>
        <applications>
            <application label="Rapid Deployment" package="com.symbol.msp" activity="com.symbol.msp.client.RDMenu"/>
            <application label="Calculator" package="com.android.calculator2" activity="com.android.calculator2.Calculator"/>
            <application label="DWDemo" package="com.symbol.datawedge" activity="com.symbol.datawedge.DWDemoActivity"/>
            <link label="ET1 Video" url="http://www.youtube.com/watch?v=ERlIzLt-h6s"/>
        </applications>
        <tools>
            <application label="Calculator" package="com.android.calculator2" activity=""/>
            <application label="Rapid Deployment" package="com.symbol.msp" activity="com.symbol.msp.client.RDMenu"/>
        </tools>
        <passwords>
            <admin></admin>
        </passwords>
        <preferences>
            <title>Enterprise Home Screen</title>
            <icon_label_background_color>#AAFFFFFF</icon_label_background_color>
            <icon_label_text_color>#FF000000</icon_label_text_color>
            <orientation></orientation>
            <bypass_keyguard>1</bypass_keyguard>
            <auto_launch_enable>0</auto_launch_enable>
            <wallpaper></wallpaper>
            <kiosk_mode_enabled>0</kiosk_mode_enabled>
            <disable_status_bar_settings_icon>1</disable_status_bar_settings_icon>
            <disable_statusbar_pulldown>0</disable_statusbar_pulldown>
            <install_shortcuts>0</install_shortcuts>
            <exit_instead_of_reboot>0</exit_instead_of_reboot>
            <airplane_option_disabled>1</airplane_option_disabled>
            <keyguard_camera_disabled>1</keyguard_camera_disabled>
            <keyguard_search_disabled>1</keyguard_search_disabled>
            <usb_debugging_disabled>1</usb_debugging_disabled>
            <system_settings_restricted>1</system_settings_restricted>
        </preferences>
    </config>

### Auto launch (optional)

Auto launch will allow you to start any number of applications at startup, but will not stop the user from pressing BACK or HOME to exit auto launched applications.

    <auto_launch>
        <application delay="8000" package="com.android.calculator2" activity=""/>
        <application delay="5000" package="com.rovio.angrybirds" activity=""/>
    </auto_launch>

The `delay` attribute will allow you to set a wait time (in milliseconds) before the specified application is launched. If your application is installed on the SD card then you must use a delay to allow for the time it takes Android to mount the SD card.

#### Auto launch preferences

    <preferences>
        <auto_launch_enable>0</auto_launch_enable>
    </preferences>

Valid node values

  0 | disable (default)
  1 | enable

| `<auto_launch_enable>` must also be set to `1` before EHS will use the `<auto_launch>` section.

### Kiosk launch (optional)

This section specifies the application that will be launched in Kiosk mode.

    <kiosk>
            <application label="Calculator" package="com.android.calculator2" activity=""/>
    </kiosk>

#### Kiosk preferences

Kiosk mode will allow you to specify one application to run at startup and will prevent the user from pressing BACK or HOME to exit that program.

    <preferences>
         <kiosk_mode_enabled>1</kiosk_mode_enabled>
    </preferences>

Valid node values

  0 | disabled (default when not specified)
  1 | enabled

| `<kiosk_mode_enabled>` must also be set to `1` in the preferences section before EHS will lock the device into the specified application.

2. | Once you have set this setting you will not be able to exit Kiosk mode unless you do one of the following: Inside a custom developed application the Android developer has the option to write code to disable and enable Kiosk Mode. This is done through an Android specific method called intent. Send the following intent to EHS…
       Intent intent = new Intent("com.symbol.enterprisehomescreen.actions.MODIFY_KIOSK_MODE");
       Intent.putExtra("enable",false);
       sendBroadcast(intent);
Change Intent.putExtra("enable",true); re-enable Kiosk mode

### Applications

This section will add icons to the "User" home screen.

    <applications>
            <application label="Calculator" package="com.android.calculator2" activity=""/>
            <link label="ET1 Video" url="http://www.youtube.com/watch?v=ERlIzLt-h6s"/>
    </applications>

#### <application> node

EHS will display the applications icon

The `label` attribute

  specifies the text that will be displayed below the application icon.

The `package` attribute

  should be set to the application’s package name.

The `activity` attribute (optional)

  should be set to the application activity.

| Some applications require an activity to be specified in order to launch. See MSP agent in main example.

| An alternative way to add an application to this section is to login as admin in EHS, long press on any icon, and answer YES to the prompt (EHS will handle adding the application to the xml configuration file). Repeating this process will remove the added application.

#### <link> node representing a web address or file

EHS will use the icon of the default Web Browser application.

The `label` attribute

  specifies the text that will be displayed below the icon.

The `url` attribute

  should be set to the full address of the web site you would like displayed (i.e. http://… or https://… or file://…). Only html files are supported under file://

The `package` attribute (optional)

  should be set to the application’s package name.

The `activity` attribute (optional)

  should be set to the application activity.

| The `package` and `activity` attributes can be used to launch the url via a specified app. For example, to open the url in the Mozilla Mobile browser, the link node would look as follows… <link label="Mozilla Mobile" url="http://www.mozilla.org/en-US/mobile/" package="org.mozilla.firefox" activity="org.mozilla.firefox.App" /> By default EHS will launch a link using the Android default browser. In order to launch different browser in EHS, the package and activity names must be specified. If the specified browser does not exist on the device, EHS will not display the link on its screen

#### <link> node representing a local or remote application added using intents

In the case of shortcuts added to remote or local applications using intents, a new link tag with the following attributes will be added to the configuration file automatically.

The `label` attribute

  represents the shortcut name. Same as the value of "Intent.EXTRA_SHORTCUT_NAME".

The `uri` attribute

  represents the intent in text format. Same as the URI representation of the intent data "Intent.EXTRA_SHORTCUT_INTENT".

The `icon` attribute

  specifies the path of the icon file stored in the device. If the extra data "Intent.EXTRA_SHORTCUT_ICON" is available in the received broadcast intent, the icon will be stored in the device as an image file.

The `icon_ref` attribute

  specifies the package name to retrieve the icon later. If the extra data "Intent.EXTRA_SHORTCUT_ICON_RESOURCE" is available in the received broadcast intent, the icon will be generated runtime using the package name. Hence no need to store the icon image in the device.

| For example, in a shortcut added to the remote application "Microsoft Excel" via Citrix Receiver, the link node would look as follows… <link label="Microsoft Excel" icon="/enterprise/usr/ehs_data/images/MicrosoftExcel.png" uri="citrixreceiver://launchapp?pid=1&inname=citrixcloud%3AMicrosoft+Excel+MS&fname=Microsoft+Excel&shortcutCookie=681181718&mobile=0&unikey=0#Intent;action=android.intent.action.VIEW;launchFlags=0x14000000;end" />

### Tools

Applications listed in this section will be displayed in the Tools screen (accessed from the context menu).

    <tools>
        <application label="Calculator" package="com.android.calculator2" activity=""/>
        <application label="Rapid Deployment" package="com.motorola.msp" activity="com.motorola.msp.client.RDMenu"/>
    </tools>

### Passwords

This section holds the admin password for EHS. The password is 256 bit AES encrypted by EHS. The password can be changed via the Tools screen once logged in as admin. Default password is blank.

    <passwords>
        <admin></admin>
    </passwords>

Tap Ok to login. It is recommended that you change the password after logging in the first time.

### Preferences

This section allows you to customize the look and feel of EHS.

#### Title

The text displayed in the title bar can be changed as follows…

    <preferences>
        <title>Enterprise Home Screen</title>
    </preferences>

#### Icon label background color

The background color of the icon labels can be changed as follows…

    <preferences>
        <icon_label_background_color>#AAFFFFFF</icon_label_background_color>
    </preferences>

#### Icon label text color

The foreground/text color of the icon labels can be changed as follows…

    <preferences>
        <icon_label_text_color>#FF000000</icon_label_text_color>
    </preferences>

| Color format Supported formats are: #RRGGBB, #AARRGGBB, "red", "blue", "green", "black", "white", "gray", "cyan", "magenta", "yellow", "lightgray" and "darkgray". For example…
    <icon_label_text_color>#75A319</icon_label_text_color>
    <icon_label_text_color>#80EF671B</icon_label_text_color>
    <icon_label_text_color>magenta</icon_label_text_color>
#RRGGBB and #AARRGGBB represent hexadecimal color values where…
AA | specifies the opacity (ranging from 00 to FF)
RR | specifies the level of RED (ranging from 00 to FF)
GG | specifies the level of GREEN (ranging from 00 to FF)
BB | specifies the level of BLUE (ranging from 00 to FF)
The following web-site may be helpful in determining the RGB values for a desired color… http://www.colorpicker.com/

#### Orientation

The orientation of EHS can be fixed by setting the following value to either "landscape" or "portrait"…

    <preferences>
        <orientation>landscape</orientation>
    </preferences>

Valid node values

  landscape |
  portrait |
  default | (default when not specified)

| Omitting this preference or leaving it blank will cause the orientation to be determined by the Android system settings.

#### Bypass keyguard

Setting the following value to one will cause EHS to bypass any keyguard/unlock screen including Mx multi-user login screen. So if Mx multi-user has to be used with EHS, bypass keyguard should not be enabled.

| If Mx multi-user has been enabled in the device and also the keyguard is bypassed, Mx will then consider it as a non-admin user throughout the system.

    <preferences>
        <bypass_keyguard>1</bypass_keyguard>
    </preferences>

Valid node values

  0 | normal
  1 | bypass (default when not specified)

| When bypass keyguard is enabled, launching a web page from a specified link or launching the web browser itself may not work at the first attempt after device is rebooted. To overcome this, either disable bypass keyguard or press on the HOME button once.

#### Wallpaper

The image EHS uses for the background can be changed by setting the following value…

    <preferences>
        <wallpaper>/enterprise/usr/mybackground.png</wallpaper>
    </preferences>

| Only Portable Network Graphics (png) format image files are supported. Images in the /enterprise/usr/ folder are supported. Images on the SD card, however, are not supported.

#### Fullscreen

EHS can be made full screen by setting the following value…

    <preferences>
        <fullscreen>1</fullscreen>
    </preferences>

Valid node values

  0 | normal (default when not specified)
  1 | fullscreen

| This only makes EHS full screen. Any apps launched from EHS will not appear full screen unless designed to do so. On Android 4.4 KitKat devices, the device status/notification bar will still be visible and could be accessed by pulling down the bar even when the EHS is made full screen. To disable this pulling down the bar, use the "Disable status bar pull down" option in EHS.

#### Admin max attempts

The maximum number of admin login attempts can be set by the following value…

    <preferences>
        <admin_max_attempts>10</admin_max_attempts>
    </preferences>

If this node is not present or contains no value, the default of ten will be used.

| When the number of consecutive failed login attempts reaches the number specified above, further login attempts will not be allowed. EHS tracks the number of consecutive failed login attempts by adding an attribute to the password admin node…
    <passwords>
        <admin attempts="10"></admin>
    </passwords>
In order to allow further login attempts, this attribute needs to be removed. This can be done by pushing a new enterprisehomescreen.xml file to the device.

#### Admin inactivity timeout

An admin inactivity timeout (in seconds, default sixty) can be specified which on expiry causes the automatic logout of admin mode…

    <preferences>
        <admin_inactivity_timeout>60</admin_inactivity_timeout>
    </preferences>

If this node is not present or contains no value, the default of sixty seconds will be used.

The minimum inactivity timeout is fifteen seconds; lower values than this will be ignored.

Setting the value to zero will disable the inactivity timeout.

| This inactivity timeout only counts down whilst EHS is in foreground. If an app is launched, i.e. EHS is no longer in foreground, the inactivity timeout is stopped and then reset once EHS returns to foreground.

#### Disable status bar Settings icon

| The "Disable status bar settings icon" is being deprecated and will be removed in the future. This feature is replaced with the new "Disable Applications" feature which can be used to disable the system Settings application. Disabling the Settings application will not remove the icon from the notification bar but clicking on the icon will not launch the application. The "Exit instead of reboot" option is also being deprecated since this feature is used in conjunction with the "Disable status bar settings icon" feature.

The Settings icon in the status/notification bar can be disabled on those devices that support this feature…

    <preferences>
        <disable_status_bar_settings_icon>1</disable_status_bar_settings_icon>
    </preferences>

Valid node values

  0 | enable
  1 | disable

When not specified, this will default to the current system setting.

| In order for this setting to take effect, the device must be rebooted. EHS will automatically reboot the device, without warning, when this setting is applied or changed.

| It is recommended that you restore/set the Settings icon before uninstalling EHS.

#### Disable status bar pulldown

The status/notification bar pulldown can be disabled via the following…

    <preferences>
        <disable_statusbar_pulldown>1</disable_statusbar_pulldown>
    </preferences>

Valid node values

  0 | enable (default when not specified)
  1 | disable

#### Exit instead of reboot

| The "Exit instead of reboot" option is also being deprecated since this feature which used in conjunction with the "Disable status bar settings icon" feature is also being deprecated. The "Disable status bar settings icon" is being deprecated and will be removed in the future. This feature is replaced with the new "Disable Applications" feature which can be used to disable the system Settings application. Disabling the Settings application will not remove the icon from the notification bar but clicking on the icon will not launch the application.

This setting is intended for use by MDMs (Mobile Device Managers), and will cause EHS to exit instead of reboot when a setting that requires a reboot is applied/changed.

    <preferences>
        <exit_instead_of_reboot>1</exit_instead_of_reboot>
    </preferences>

Valid node values

  0 | reboot (default when not specified)
  1 | exit

| If EHS has been set as the default launcher, then the OS will restart EHS after it exits.

#### Disable applications

Any system or custom application in the device can be disabled/enabled using the following settings. The Application must be defined by its package name. Please note the package name of an Android application may not be the same on different OS versions.

    <preferences>
            <apps_disabled>
                    <application package="com.android.settings"/>
                    <application package="com.android.quicksearchbox"/>
            </apps_disabled>
            <apps_enabled>
                    <application package="com.android.gallery3d"/>
            </apps_enabled>
    </preferences>

- To disable/enable an application, its package name should be given under "apps_disabled" or "apps_enabled" respectively.

- In enabling/disabling apps, EHS will treat the Settings app and Search app differently to that of other apps. If Settings or Search app is given under "apps_disabled" or "apps_enabled", EHS will disable or enable it for users only, but not for Admin. Hence for Admin, both Settings and Search apps will be always enabled. But for any other app given under "apps_disabled" or "apps_enabled", EHS will disable or enable them for both Users and Admin.

- When the EHS configuration file is manually updated, in order to re-enable after disabling an application, the application must be listed under "apps_enabled" in the configuration file. Failure to add this entry will keep the application in disabled state.

- If either of these nodes is not found in the EHS configuration file, EHS will disable the system settings and search applications by default.

- If the node is present, the apps defined in the configuration file will be enabled/disabled instead of EHS defaults.

- If the same application name is present under both "apps_disabled" and "apps_enabled" that app will be disabled.

| Uninstalling EHS will not revert the app enabled/disabled settings to the previous state. Make sure to set the app state to the original state, if required, before uninstalling EHS. The following apps are normally enabled by default.

    <preferences>
            <apps_enabled>
                    <application package="com.android.settings"/>
                    <application package="com.android.quicksearchbox"/>
            </apps_enabled>
    </preferences>

#### Disable Airplane/Flight option

Airplane/Flight option under power menu can be disabled on those devices that support this feature.

    <preferences>
            <airplane_option_disabled>1</airplane_option_disabled>
    </preferences>

Valid node values

  0 | enable
  1 | disable (default when not specified)

#### Disable Camera on keyguard/unlock screen

Camera application can be disabled/enabled on the keyguard/unlock screen using the following setting, so that the camera application launch can be blocked/allowed from the keyguard screen.

| Disabling/enabling Camera in keyguard will have effect only when the device keyguard has a Camera icon on it and also the camera application is enabled in the device. If there is no Camera icon on the keyguard or it’s already disabled in the device, this setting will have no effect.

    <preferences>
            <keyguard_camera_disabled>1</keyguard_camera_disabled>
    </preferences>

Valid node values

  0 | enable
  1 | disable (default when not specified)

#### Disable Search on keyguard/unlock screen

Search application can be disabled/enabled on the keyguard/unlock screen using the following setting, so that the Search application launch can be blocked/allowed from the keyguard screen.

| Disabling/enabling Search in keyguard will have effect only when the device keyguard has a Search icon on it and also the Search application is enabled in the device. If there is no Search icon on the keyguard or it’s already disabled in the device, this setting will have no effect.

    <preferences>
            <keyguard_search_disabled>1</keyguard_search_disabled>
    </preferences>

Valid node values

  0 | enable
  1 | disable (default when not specified)

#### Install shortcuts

Setting the following value to one will cause EHS to allow intents to add shortcuts to remote and local applications. By default this is disabled, means listening to these intents are disabled in EHS.

    <preferences>
       <install_shortcuts>0</install_shortcuts>
    </preferences>

Valid node values

  0 | disable (default when not specified)
  1 | enable

#### Disable USB Debugging (ADB) in User mode

USB debugging (Android Debug Bridge communication) can be disabled/enabled for EHS non-admin users using the following setting. In EHS Admin mode ADB will always be enabled and this setting is to enable/disable ADB for User mode.

    <preferences>
            <usb_debugging_disabled>1</usb_debugging_disabled>
    </preferences>

Valid node values

  0 | enable
  1 | disable (default when not specified)

| Uninstalling EHS will not revert the USB Debugging (ADB) state to the previous state. Make sure to set the ADB state to the original state, if required, before uninstalling EHS.

#### Restrict System settings in User mode

Android System settings can be restricted for EHS non-admin users using the following setting. Once restricted EHS users would have access only to a reduced set of system settings such as Sound, Display and About phone. Otherwise full set of settings is accessible.

    <preferences>
            <system_settings_restricted>1</system_settings_restricted>
    </preferences>

Valid node values

  0 | enable
  1 | disable (default when not specified)

| This feature is available only on the latest devices such as TC55 KitKat.

| To make use of this setting and to see its effect, System settings application has to be enabled in advance via "Disable applications" feature in EHS. And also, uninstalling EHS will not revert the Restricted settings state to the previous state. Hence make sure to set it to the original state, if required, before uninstalling EHS.

### Install shortcuts using intents

EHS allows intents to add shortcuts to remote and local applications in the device. For this, EHS setting Install shortcuts should be enabled in advance. Then EHS will listen to the Android broadcast intent "com.android.launcher.action.INSTALL_SHORTCUT". When EHS receives this broadcast intent, it will create a shortcut on the user screen using the data extracted from the received intent. The same data will be written to the configuration file under "Applications" node. Please refer to <link> node for more information.

| Adding duplicate shortcuts to the same local or remote application is allowed. But shortcuts being added before installing EHS or before making EHS the default launcher will not be considered. To remove existing shortcuts from user screen, the corresponding "link" tag has to be deleted from the configuration file.

## EHS Operating Modes

### Introduction

EHS supports two operating modes:

Unsecure Mode | In the Unsecure mode, EHS will not determine if the configuration file was created by the authorized person. EHS will import and act upon any configuration file provided the name of the file and its contents meet EHS requirements.
Secure Mode | In the Secure mode, EHS will accept only the signed configuration file. The Secure mode is provided to prevent unauthorized persons from getting control of EHS by accessing and modifying the EHS configuration file (enterprisehomescreen.xml). To operate in the Secure mode, EHS requires the signed configuration file (enterprisehomescreen.xml) and the matching signature file (enterprisehomescreen.pem).

### Installing EHS to run in Unsecure mode

- Install and run the EHS APK as described in Installation section.

- If the EHS configuration file is provided in the /enterprise/usr folder without the .pem file, EHS will import the file and run in the Unsecure mode. Refer to Configuration for instructions on creating the configuration file. WARNING: In the Unsecure mode, the configuration files will remain in the /enterprise/usr folder.

- If the EHS configuration file is not provided, EHS will run in the Unsecure mode using the default settings.

- Follow the above steps for manual as well as MDM deployments

- To determine if EHS is running in Unsecure mode, follow the directions provided in Identifying Operating Mode

### Installing EHS to run in Secure mode

- Create the Device Certificate as described in Creating Device certificate and Private Key

- Install the Device Certificate on the device as described in Installing Device certificate

- Create the EHS configuration file (enterprisehomescreen.xml) as described in the Configuration section.

- Sign the EHS configuration file as described in Signing EHS configuration file. A successful signing produces the matching signature file (enterprisehomescreen.pem).

- Copy the signed configuration and signature files to the /enterprise/usr folder.

- Install and run the EHS APK as described in Installation section.

- EHS will attempt to match the configuration and signatures files with the device certificate.

- If the matching is successful, EHS will run in the Secure mode and import the configuration file. WARNING: In the secure mode, the configuration and signature files will be removed from the /enterprise/usr folder.

- If the matching is unsuccessful, the device will go into the Lock down state as described in Lock down state.

- Follow the above steps for manual as well as MDM deployments

- To determine if EHS is running in Secure mode, follow the directions provided in Identifying Operating Mode

- To retrieve the configuration file when the device is in secure mode, use the Export Configuration File option available under Tools menu once logged in as Admin.

### Switching to Secure mode when running in Unsecure Mode

- Create the Device Certificate as described in Creating Device certificate and Private Key

- Install the Device Certificate on the device as described in Installing Device certificate

- Create the EHS configuration file (enterprisehomescreen.xml) as described in Installation section.

- Sign the EHS configuration file as described in Signing EHS configuration file. A successful signing produces the matching signature file (enterprisehomescreen.pem).

- Copy the signed configuration file to the /enterprise/usr folder.

- Copy the signature files to the /enterprise/usr folder.

| The configuration (.xml) file must be copied first and then the Signature file (.pem). Failure to follow this order will result in Lock down state , but for a brief period only. It will come out from lock down state once the configuration file is copied.

- EHS will attempt to match the configuration and signatures files with the device certificate.

- If the matching is successful, EHS will run in the Secure mode.

- If the matching is unsuccessful, the device will go into the Lock down state as described in the Lock down state.

- Follow the above steps for manual as well as MDM deployments

- To determine if EHS is running in Secure mode, follow the directions provided in Identifying Operating Mode

### Switching to Unsecure mode when running in Secure Mode

- Uninstall EHS. Only the EHS Admin can uninstall EHS.

- OR

- Enterprise reset the device. Refer to the device user guide for instructions on Enterprise resetting the device. Follow the instructions under Installing EHS to run in Unsecure mode section.

- OR

- Go to device "System Settings" → "Apps", select EHS, click on Clear Data.

### Creating Device certificate and Private Key

- Create a device certificate (caroot.pem) and a private key file (privatekey.pem) using OpenSSL as described below. To install OpenSSL, follow the instructions under Appendix: Installing OpenSSL tool on Windows PC

  - CMD> C:\OpenSSL-Win32\bin\openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout privatekey.pem -out caroot.pem

| Use same version of OpenSSL to generate certificate and to sign configuration file.

### Installing Device certificate

- To install the device root certificate (eg. caroot.pem) first you have to create certificate.xml file as shown below.

    <?xml version="1.0" encoding="UTF-8"?>
    <certificate>
            <install>
                    <source>/sdcard/caroot.pem</source>
                    <alias>CARootCert1</alias>
            </install>
    </certificate>

- Copy the created caroot.pem on the device sdcard.

- Push certificate.xml file using following ADB command or FileBrowser. Then the device root certificate will be installed in the device.

  - CMD>adb push certificate.xml /enterprise/device/settings/mdm/autoimport/

- Use following command to pull Results.xml, which indicates whether the certificate installation is successful or not.

  - CMD>adb pull /enterprise/device/settings/mdm/autoimport/Results.xml.

### Signing EHS configuration file

- Sign the EHS configuration file (enterprisehomescreen.xml) using the private key (privatekey.pem). The private key is created as described in Creating Private Key . The signing of the Configuration file will create the EHS signature (enterprisehomescreen.pem) file.

  - CMD>C:\OpenSSL-Win32\bin\openssl dgst -sign privatekey.pem -out enterprisehomescreen.pem enterprisehomescreen.xml

### Identifying Operating Mode

- To identify the current Operating Mode of the EHS, log in as Admin and view the Admin UI. The field Secure Mode will be set to ON when in Secure mode. This field will be set to OFF if EHS is running in Unsecure mode. The Secure Mode field is read-only and cannot be used to change the operating mode. Also, there is no entry in the configuration file that specifies the operating mode.

### Additional information on Operating Mode

- Logging : EHS logs the activities in the enterprisehomescreen.log file. Some of these activities are errors, exceeding allowed Admin login attempts and switching the Operating mode.

- In both Secure and Unsecure modes, the EHS admin is allowed to change/reset the password.

### Lock down state

- To operate in the Secure mode, the signed configuration file (enterprisehomescreen.xml ) and the matching signature file (enterprisehomescreen.pem) must be provided in the/enterprise/usr folder. EHS will attempt to verify these files against the corresponding device certificate installed on the device. If the verification fails, EHS will go into the Lock down state. In the Lock down state, the Lock down screen will appear. This screen will display the reason for locking down the device and no user activity will be permitted except an option for the EHS Admin to log in.

### Exiting the Lock down state

- One of the following methods can be used to exit the Lock down state:

  - Copy valid EHS configuration and signature files to the /enterprise/usr folder. EHS will exit the lock down state, import the configuration file and function in the Secure mode. The valid files can be deployed using MDM or copied manually by the EHS Admin.

  - Delete the signature file from the /enterprise/usr folder. EHS will exit the Lock down state and enter into the secure mode. This method will work only if EHS is already running in the Secure mode. EHS will remain in the lock down state if EHS was previously running under the Unsecure mode and an unsuccessful attempt was made to switch to the Secure mode

| If the number of unsuccessful Admin login attempts reached the maximum limit specified in the EHS Configuration file, EHS will go into permanent Lock down state. The only way to exit is to copy valid configuration and signature files or delete the existing signature file remotely via MDM.

### How EHS reacts to file operations

Current mode | Operation | Results | Recovery
Unsecure mode | Copy a new enterprisehomescreen.xml file into /enterprise/usr folder | New configuration takes effect. Still the device is running in unsecure mode. |
Unsecure mode | Copy an invalid pem file (i.e. this pem file does not match the xml file in /enterprise/usr folder) | Lock down screen shows up immediately | Delete the pem file in /enterprise/usr folder via admin login to the device or remotely . Device will resume in unsecure mode with existing configuration.
Unsecure mode | Copy a new xml file first and then the pem file (corresponding to that new xml file) into /enterprise/usr folder | Once the xml file is detected the new configuration takes effect in unsecure mode. When the pem file is copied: If signature verification is SUCCESS : Device goes to secure mode. If signature verification is FAIL: Lock down screen shows up immediately with Error. |
Unsecure mode | Copy a new pem file first and then the xml file (corresponding to that new pem file) into /enterprise/usr folder | As soon as pem file is copied the device will go to lock down state. Once the relevant xml file is copied, lock down screen will vanish and device will go to secure mode with new configuration taking effect. WARNING: The recommended way is to copy the xml file first and the pem file the second |

Current mode | Operation | Results | Recovery
Secure mode | Copy a new xml file into /enterprise/usr folder | New configuration does NOT take effect, since the relevant pem file has not been copied. Hence the device remains in the previous configuration, in secure mode. Note: Device does not go to lock down state in this case" |
Secure mode | Copy a new xml file and the pem file (corresponding to that new xml file) into /enterprise/usr folder | If signature verification is SUCCESS: Device remains in secure mode. New configuration takes effect. If signature verification is FAIL: New configuration does NOT take effect.Device goes to lock down state." | Delete the xml file and pem file in /enterprise/usr folder via admin login to the device or remotely. Device will resume in secure mode with previous configuration."
Secure mode | Copy only a pem file into /enterprise/usr folder. | Lock down screen shows up immediately | Option 1: Copy the xml file (corresponding to the pem file) via Admin login to the device or remotely. Lock down screen will vanish immediately and the new configuration will take effect. Option 2: Delete the pem file in /enterprise/usr folder: lock down screen will vanish immediately and the device will remain in previous configuration."

Current state | Operation | Results
lock down state | Admin logins to the device and copy a new xml file and the relevant pem file via file browser in the device. | If signature verification is SUCCESS: Device enters into secure mode. New configuration takes effect. If signature verification is FAIL: Lock down screen shows up again. New configuration does NOT take effect.
lock down state | Copy a new xml file and the relevant pem file remotely. | If signature verification is SUCCESS: Lock down screen vanishes abruptly. Device enters into secure mode. New configuration takes effect. If signature verification is FAIL: Lock down screen remains. New configuration does NOT take effect.
lock down state | Delete the pem file in /enterprise/usr folder via admin login to the device or remotely. | If the device was in secure mode previously: Lock down screen vanishes and the device will resume in secure mode with previous configuration. If the device was in unsecure mode previously: Lock down screen vanishes and the device will resume in unsecure mode with previous configuration.
lock down state | Do not change any files in the /enterprise/usr folder. Then Uninstall EHS and Install EHS again | When EHS is launched, lock down screen shows up in the device.
lock down state | Delete the xml file and pem file in /enterprise/usr folder. Then Uninstall EHS and Install EHS again | EHS is launched in unsecure mode

## Important notes

### Recent apps list

- Any apps/activities launched from EHS will not be added to Android’s recent app list.

- However, should a launched app/activity subsequently launch another app/activity then that may appear in Android’s recent app list (this depends on the implementation of the former app/activity).

- To clear the recent apps list either reboot the device or press and hold the Home button until the list of recent apps appears, then press and hold an app in the list until a context menu appears, then select Remove from list and repeat for the remaining apps.

- If previously used app list is not deleted using one of the above two methods, it may get activated back when the Back button on the device is pressed and even the default home screeen can be seen instead of the Enterprise Home Screen.

### Using EHS with MX Multi-user

- In order to use the Mx multi-user feature while using EHS, the bypass keyguard setting should be disabled. If the bypass keyguard is enabled when using Mx Multi-user, the multi-user log-in screen will not be displayed. Refer to Bypass keyguard for more information.

- If Mx multi-user feature is enabled while using EHS, exposing "Restricted" or "Full" System Settings in EHS will be decided by the current Mx User being logged in. Then Mx Admin will always have the "Full" settings while Mx non-admin will have only the "Restricted" settings. By default, options available in the Restricted System Settings are limited to Sound, Display and About phone.

### Disable applications

- The Search and Settings apps are automatically enabled when the admin logs in, even if these apps are disabled for the User. All other apps are disabled when the admin logs in if the apps are disabled for User.

### Using kiosk mode

- By default, EHS disables USB debugging in the "User" mode and enables USB debugging in the "Admin" mode. From EHS 2.0 onwards, if the kiosk mode is planned to be disabled via USB debugging, this USB debugging feature should be enabled for "User" mode in advance.

### EHS internal information for third party applications

- EHS installer:

  - Package name: com.symbol.ehsinstaller

  - Main activity/class name: com.symbol.ehsinstaller.EHSinstaller

- EHS app for Symbol devices:

  - Package name: com.symbol.enterprisehomescreen

  - Main activity/class name: com.symbol.enterprisehomescreen.HomeScreenActivity

- EHS app for Motorola devices:

  - Package name: com.motorolasolutions.enterprisehomescreen

  - Main activity/class name: com.motorolasolutions.enterprisehomescreen.HomeScreenActivity

## Usage notes

1. Color picker preferences for icon label background/text color are disabled for screen sizes less than 480 pixels in any axis. Hence use EHS configuration file to change the color in those low resolution devices.

2. On Android 4.4 KitKat devices, the device status/notification bar will still be visible and could be accessed by pulling down the bar even when the EHS is made full screen. To disable this pulling down the bar, use the "Disable status bar pull down" option in EHS.

3. On Android 4.4 KitKat devices, settings such as Airplane mode, Wi-Fi, Bluetooth can be turned ON/OFF via Quick Settings menu in the notification drop down. To disable this feature, use the "Disable status bar pull down" option in EHS.

4. While in the User mode in EHS, the screen shot of the current foreground screen can be captured using the "Volume down and Power button" keys simultaneously and obtain access to Gallery app. To disable this feature, use the "Disable Applications" option in EHS to disable the Gallery app on the device.

5. Make sure the shortcut created using the Intent is valid in all circumstances. EHS will add the shortcut created via Intent to the EHS configuration file similar to the manually created shortcuts. If the EHS configuration file is copied to other devices manually or using MDM, the shortcuts will be created on other devices as well. EHS will not check the validity of the shortcut.

6. Starting from version 2.0, EHS comes as an Installer apk. Uninstalling the EHS Installer apk from the device will automatically uninstall the EHS apk as well. Please refer to Uninstallation for more information. If you still want to uninstall EHS apk alone, use one of the following options to uninstall EHS apk from the devices with Android version 4.4.3 and above:

   - Settings → Home → select EHS from the list → click the trash icon next to it → EHS will be uninstalled directly.

   - Settings → Apps → select EHS from the list → click on Clear defaults → press on back button on the device → click on EHS app again → click on Uninstall button → EHS will be uninstalled.

## Appendix: Installing OpenSSL tool on Windows PC

1. Download OpenSSL tool for W32/W64 bit machine from the below URL

   - http://slproweb.com/products/Win32OpenSSL.html

   - Version: OpenSSL 1.0.1g or above

2. Install the tool on your PC by double clicking on exe file.

3. During Installation, Setup will warn for installation of Visual C++ 2008. We do not require it so, just cancel (click on cancel button) and proceed further to complete installation.

4. Open the command prompt. Go to the OpenSSL installed folder. By default the OpenSSL is installed in C:\OpenSSL-Win32\

   - $ cd C:\OpenSSL-Win32\bin

5. Set the OpenSSL configuration Environment variable by executing the following command in command prompt.

   - $ Set OPENSSL_CONF=C:\OpenSSL-Win32\bin\openssl.cfg